Gate or clearly label mock and fabricated data returned by API endpoints - #60

Summary

Several API modules returned hardcoded/fabricated data presented as real: oracle prices, cross-chain arbitrage feeds, simulated bot PnL, ZK-proof "verification", synthetic price history, and fake backfill export URLs. This PR adds a single shared framework that blocks fabricated responses by default and only serves them — always explicitly annotated mock: true — when an operator opts in via MOCK_DATA=true.

What changed

• New src/config/mockData.ts: isMockDataEnabled(), annotateMock(), and sendMockGated() — the shared gating/annotation primitives. Off by default; MOCK_DATA=true (or ENABLE_EXPERIMENTAL=true) opts in.
• src/api/oracle-feeds.ts: GET /assets/:assetPair/price now blocks the fabricated price by default (404) instead of always returning it.
• src/api/arbitrage.ts: GET /cross-chain/opportunities, GET /cross-chain/bridges, and the entire simulated-bot family (POST /bot/deploy, GET /bot/:address/status, POST /bot/:address/config, POST /bot/:address/pause) are gated — these fabricate cross-chain prices and random PnL drift.
• src/api/data-market.ts: GET /prices/history (synthetic sine-wave series) is gated. verifyZkProof() now only returns true in MOCK_DATA mode — outside it, a "ZK-proof" is never falsely reported as cryptographically valid (real verification isn't implemented), and the challenge/verify responses disclose this (verificationMethod, or a note when a zk_proof challenge is treated as failed).
• src/api/backfill.ts: a backfill job can no longer "complete" with a fake download URL/record count outside MOCK_DATA mode — it fails honestly with a clear errorMessage instead. When it does complete (mock mode only), the response is marked mock: true.
• src/api/reputation.ts: the leaderboard endpoint no longer needs gating at all — it was substituting a hardcoded constant (transactionCount: 10 for every profile) as the input to real score computation. It now derives real per-address activity via the existing fetchProfileData() used by every other per-address endpoint, so no fabricated data feeds into the leaderboard.
• src/api/sandwich.ts: cosmetic — a variable named mockPatterns actually held real DB-derived data; renamed to recentSandwichPatterns to stop it looking like fabricated data (audit false positive).
• src/api/freeze.ts, src/api/predict.ts: one-line comment rewords (removed a stray "mock" mention describing real, non-fabricating code) so the new repo-wide CI guard doesn't false-positive on unrelated files.
• OpenAPI: added @swagger blocks (with x-experimental: true) for the newly-gated arbitrage and data-market endpoints, and updated the oracle-feeds price doc. Registered Oracle Feeds, Arbitrage, and Data Market tags in src/indexer/swaggerSpec.ts.
• CI guard (scripts/check-mock-gating.ts, npm run check:mock-gating, wired into the lint job in .github/workflows/ci.yml): fails if any src/api file mentions "mock" without importing the shared framework — so a new ungated fabricated-data endpoint can't ship silently.
• README.md: new "Experimental & Mock Data" section documenting the MOCK_DATA flag, the gated-endpoint table, and the CI guard.
• Tests: tests/api/mock-data-gating.test.ts (blocked-by-default / labeled-when-enabled behavior for oracle-feeds, arbitrage cross-chain + bot, data-market price history; leaderboard now calls fetchProfileData per profile instead of fabricating), tests/scripts/check-mock-gating.test.ts (guard fixture tests, including the "fails on a deliberately ungated mock file" acceptance case), plus a small update to the existing tests/archival-routes.test.ts and tests/orphaned-routers-integration.test.ts to match the new gated behavior. New test files are wired into the npm test allowlist.

Interpretation notes (ambiguous/overlapping parts of the issue)

• src/api/flash-loans.ts's /mempool endpoint is called a "stub" in the issue body, but on inspection it already returns an honest empty state (pendingHighRisk: []) with a clear explanatory message — no fabricated data is actually returned, so no code change was needed there.
• src/api/sandwich.ts's "mock patterns" turned out to be real DB-derived data with a misleading variable name, not fabricated data — fixed by renaming rather than gating.
• The CI guard is intentionally repo-wide (not scoped to just the 7 named files) since the issue asks for a durable guard against future ungated mock endpoints anywhere in src/api; this required two incidental comment rewords in unrelated files (freeze.ts, predict.ts) to remove stale "mock" mentions that would otherwise false-positive the new check.

Verification performed

Ran locally against this branch (Windows dev box; CI runs the same commands on ubuntu-latest):

• npm run build — clean.
• npm run build -- --noEmit — clean (matches the lint job's type-check step).
• npm run typecheck:scripts — clean.
• npm run lint (invoked directly as eslint "src/**/*.ts" "tests/**/*.ts" --max-warnings 400 due to a local shell quoting quirk with npm run; identical to what CI's lint job runs) — 0 errors, 322 pre-existing warnings (well under the 400 cap; none in any file this PR touches).
• npm run check:mock-gating (new) — passes: no ungated mock/fabricated data in src/api.
• npm run validate:prisma — passes, 431 valid field references, 0 phantom fields.
• npm test (the exact CI allowlist, now including the 2 new test files) — 9 test files / 200 tests passed.
• tests/archival-routes.test.ts (not in the CI allowlist, but touched by this PR) — 33/33 tests passed.

Test plan

• GET /oracle-feeds/assets/XLM-USD/price → 404 + mock: true by default; 200 + labeled price with MOCK_DATA=true.
• GET /arbitrage/cross-chain/opportunities / /bridges → gated the same way.
• POST /arbitrage/bot/deploy (and status/config/pause) → gated the same way.
• GET /data-market/prices/history → gated the same way.
• Reputation leaderboard → fetchProfileData is called per profile instead of a hardcoded constant.
• CI guard fails on a deliberately-added ungated mock file (fixture test), passes on one that imports the framework, and passes against the real src/api tree.
• Backfill: existing archival-routes.test.ts case updated to assert mock: true on a completed request.

Known pre-existing issues (not touched by this PR)

• npm run validate-routes already fails on upstream main (10 orphaned routers — flash-loans.ts, freeze.ts, predict.ts, sandwich.ts, etc. — plus a stale PENDING_SCHEMA_ROUTERS warning for webhooks.ts). This script isn't wired into ci.yml; unrelated to this change.
• npm run audit:indexes already reports pre-existing FK fields without indexes across many unrelated models. Not wired into ci.yml; no schema changes in this PR.
• A full tsc --noEmit over all of src/**/*.ts (broader than the project's own tsconfig.json include, which only follows what's reachable from src/index.ts/src/indexer/run.ts) surfaces pre-existing type errors in src/api/reputation.ts and elsewhere, unrelated to the lines this PR touches — these files are simply outside the compiled/type-checked graph already, both before and after this change.

Closes #7